[−][src]Crate libp2p

Libp2p is a peer-to-peer framework.

Major libp2p concepts

Here is a list of all the major concepts of libp2p.

Multiaddr

A Multiaddr is a self-describing network address and protocol stack that is used to establish connections to peers. Some examples:

  • /ip4/80.123.90.4/tcp/5432
  • /ip6/[::1]/udp/10560/quic
  • /unix//path/to/socket

Transport

Transport is a trait for types that provide connection-oriented communication channels based on dialing to or listening on a Multiaddr. To that end a transport produces as output a type of data stream that varies depending on the concrete type of transport.

An implementation of transport typically supports only certain multi-addresses. For example, the TcpConfig only supports multi-addresses of the format /ip4/.../tcp/....

Example (Dialing a TCP/IP multi-address):

use libp2p::{Multiaddr, Transport, tcp::TcpConfig};
let tcp = TcpConfig::new();
let addr: Multiaddr = "/ip4/98.97.96.95/tcp/20500".parse().expect("invalid multiaddr");
let _conn = tcp.dial(addr);

In the above example, _conn is a Future that needs to be polled in order for the dialing to take place and eventually resolve to a connection. Polling futures is typically done through a tokio runtime.

The easiest way to create a transport is to use build_development_transport. This function provides support for the most common protocols but it is also subject to change over time and should thus not be used in production configurations.

Example (Creating a development transport):

let keypair = libp2p::identity::Keypair::generate_ed25519();
let _transport = libp2p::build_development_transport(keypair);
// _transport.dial(...);

The keypair that is passed as an argument in the above example is used to set up transport-layer encryption using a newly generated long-term identity keypair. The public key of this keypair uniquely identifies the node in the network in the form of a PeerId.

See the documentation of the Transport trait for more details.

Connection Upgrades

Once a connection has been established with a remote through a Transport, it can be upgraded. Upgrading a transport is the process of negotiating an additional protocol with the remote, mediated through a negotiation protocol called multistream-select.

Example (noise + yamux Protocol Upgrade):

use libp2p::{Transport, core::upgrade, tcp::TcpConfig, noise, identity::Keypair, yamux};
let tcp = TcpConfig::new();
let id_keys = Keypair::generate_ed25519();
let noise_keys = noise::Keypair::<noise::X25519Spec>::new().into_authentic(&id_keys).unwrap();
let noise = noise::NoiseConfig::xx(noise_keys).into_authenticated();
let yamux = yamux::Config::default();
let transport = tcp.upgrade(upgrade::Version::V1).authenticate(noise).multiplex(yamux);

In this example, transport is a new Transport that negotiates the noise and yamux protocols on all connections.

Network Behaviour

The NetworkBehaviour trait is implemented on types that provide some capability to the network. Examples of network behaviours include:

  • Periodically pinging other nodes on established connections.
  • Periodically asking for information from other nodes.
  • Querying information from a DHT and propagating it to other nodes.

Swarm

A Swarm manages a pool of connections established through a Transport and drives a NetworkBehaviour through emitting events triggered by activity on the managed connections. Creating a Swarm thus involves combining a Transport with a NetworkBehaviour.

See the documentation of the core module for more details about swarms.

Using libp2p

The easiest way to get started with libp2p involves the following steps:

  1. Creating an identity Keypair for the local node, obtaining the local PeerId from the PublicKey.
  2. Creating an instance of a base Transport, e.g. TcpConfig, upgrading it with all the desired protocols, such as for transport security and multiplexing. In order to be usable with a Swarm later, the Output of the final transport must be a tuple of a PeerId and a value whose type implements StreamMuxer (e.g. Yamux). The peer ID must be the identity of the remote peer of the established connection, which is usually obtained through a transport encryption protocol such as noise that authenticates the peer. See the implementation of build_development_transport for an example.
  3. Creating a struct that implements the NetworkBehaviour trait and combines all the desired network behaviours, implementing the event handlers as per the desired application's networking logic.
  4. Instantiating a Swarm with the transport, the network behaviour and the local peer ID from the previous steps.

The swarm instance can then be polled e.g. with the tokio library, in order to continuously drive the network activity of the program.

Re-exports

pub use bytes;
pub use futures;
pub use self::simple::SimpleProtocol;

Modules

bandwidth
core

Transports, upgrades, multiplexing and node handling of libp2p.

deflate
dns

libp2p-dns

floodsub

Implements the floodsub protocol, see also the: spec.

gossipsub

Gossipsub is a P2P pubsub (publish/subscription) routing layer designed to extend upon flooodsub and meshsub routing protocols.

identify

Implementation of the Identify protocol.

identity

A node's network identity keys.

kad

Implementation of the libp2p-specific Kademlia protocol.

mdns

mDNS is a protocol defined by RFC 6762 that allows querying nodes that correspond to a certain domain name.

mplex
multiaddr
multihash

Multihash

noise

Noise protocol framework support for libp2p.

ping

This module implements the /ipfs/ping/1.0.0 protocol.

plaintext
pnet

The pnet protocol implements Pre-shared Key Based Private Networks in libp2p, as specified in the spec

request_response

Generic request/response protocols.

simple
swarm

High level manager of the network.

tcp

Implementation of the libp2p Transport trait for TCP/IP.

uds

Implementation of the libp2p Transport trait for Unix domain sockets.

wasm_ext

Implementation of the libp2p Transport trait for external transports.

websocket

Implementation of the libp2p Transport trait for Websockets.

yamux

Implements the Yamux multiplexing protocol for libp2p, see also the specification.

Macros

build_multiaddr

Easy way for a user to create a Multiaddr.

Structs

Multiaddr

Representation of a Multiaddr.

PeerId

Identifier of a peer of the network.

Enums

TransportError

An error during dialing or listening on a Transport.

Traits

InboundUpgrade

Possible upgrade on an inbound connection or substream.

InboundUpgradeExt

Extension trait for InboundUpgrade. Automatically implemented on all types that implement InboundUpgrade.

OutboundUpgrade

Possible upgrade on an outbound connection or substream.

OutboundUpgradeExt

Extention trait for OutboundUpgrade. Automatically implemented on all types that implement OutboundUpgrade.

Transport

A transport provides connection-oriented communication between two peers through ordered streams of data (i.e. connections).

TransportExt

Trait automatically implemented on all objects that implement Transport. Provides some additional utilities.

Functions

build_development_transport

Builds a Transport that supports the most commonly-used protocols that libp2p supports.

build_tcp_ws_noise_mplex_yamux

Builds an implementation of Transport that is suitable for usage with the Swarm.

build_tcp_ws_pnet_noise_mplex_yamux

Builds an implementation of Transport that is suitable for usage with the Swarm.

Type Definitions

Swarm

Contains the state of the network, plus the way it should behave.

Derive Macros

NetworkBehaviour

Generates a delegating NetworkBehaviour implementation for the struct this is used for. See the trait documentation for better description.